Skip to main content

Set up the Template

The app you will use as a template is in the dev-base-build GitHub repo. It implements basic functionality, such as user authentication, and can be used as a starter kit.

Create a project​

First you need to create a project for your simulation.

Follow these steps:

  1. Log in to Epicenter.
  2. On your organization's home page, create a new project.
  3. Create a workshop.
  4. Add users to the workshop.
tip

It is a good practice to add at least one participant user and one facilitator user.

Clone the template​

Download the application files on your development machine:

  1. Clone the https://github.com/forio/dev-base-build repository.
  2. In the local folder, run:
    1. git fetch --all to download all branches
    2. git checkout example to switch to the Bicycle Sales example branch.
  3. To install the dependencies, run npm install.

Finish set-up​

  1. Edit the variable values in your application's .env file:
    1. VITE_PROJECT_NAME - this can be displayed in your application's UI.
    2. VITE_DEV_ACCOUNT_SHORT_NAME - this value must match the account short name on the Epicenter dashboard.
    3. VITE_DEV_PROJECT_SHORT_NAME - this should match the project short name in the Epicenter dashboard.
    4. VITE_DEV_API_HOST - the URL of the API server where your application will make requests.
  2. Upload the model and the .ctx2 file from the application's /model directory to Epicenter:
    1. Open the project in the dashboard.
    2. Click Project Files.
    3. On the Model tab, update the files.
tip

The VITE_DEV variables in the .env file are required only for your app's local instance. Once you deploy the application interface to Epicenter, the values will be inferred from the project's URL.

warning

You must upload the model files to Epicenter, even when running the application UI on your machine.

Run the application​

Local instance​

To start the app in development mode:

  1. In command line, go to your local dev-base-build folder.
  2. Run npm run dev.

The application runs on http://localhost:8888/.

Deploy to Epicenter​

To run your application on Epicenter:

  1. In command line, go to your local dev-base-build folder.
  2. Run npm run build.
  3. Open your project in the Epicenter dashboard.
  4. Click Project Files.
  5. On the Interface tab:
    1. Delete all existing files.
    2. Upload the contents of your application's /public folder.
  6. In the dashboard, click Run Project.

Application files​

This is a brief overview of some of the components of the template application.

  • The /src/main.tsx file defines how requests are routed to the different parts of the application.
    • RequireFocusedAuth checks that the user is authenticated.
    • PlayerShell is loaded for a participant.
    • FacilitatorShell is loaded when a facilitator logs in to the application.
    • PlayerHome defines the elements on the participant's page in the sim. It gets variables from a RunQuery.
  • Files in /src/query directory contain wrappers around the JS library adapters.
    • In run.ts, queryOptions defines how to fetch the data for the sim and how to cache it locally. queryFn fetches the data.
    • In auth.ts, useLogin() calls the authAdapter.login() function.
  • The /src/routs directory contains components that handle various use cases. For example, /src/routs/login/ handles login and password reset.